RAPTOR API DOCUMENTATION

Introduction
Licencing
RAPTOR Functions, Equates and Variables
RAPTOR Application Files
RAPTOR.O Function Calls
Teamtap Functions
Dynamic Objects
- Dynamically redefining objects
- Dynamic Object Culling
Non-RAPTOR Objects
RAPTOR_user_vbi (System Hook)
RAPTOR Initialization File (_RAPINIT.S)
- RAPTOR List Data
Hooks to internal registers, counters and flags
RAPTOR Debug Console
RAPTORMT.O Function Calls
RAPTOR235.O Function Calls
RAPTORGD.O Function Calls
RAPTORLSP.O Function Calls

Introduction

The RAPTOR Engine™ is a software package intended for use by developers on the Atari Jaguar 64-bit Multimedia System. It provides a HAL (Hardware Abstraction Layer) to allow you to concentrate on your game rather than how the Jaguar hardware functions. Technology has been built into the RAPTOR Engine™ to simplify its use, whilst providing flexibility and minimizing main system bus access.

Licencing

Definitions

“The Software” refers to the RAPTOR Engine, which is provided as assembled binary objects for use on the Atari Jaguar 64-bit Multimedia System.
“Author(s)” refers to the group REBOOT (http://reboot.atari.org)

Licence

This software is provided free of charge to anyone and everyone. REBOOT accepts no responsibility for damage or loss by its use or misuse. REBOOT grants you the right to use this software within your own works provided that:

Clear identification of the use of this software is included within your own works, either by use of the currently approved logo provided, or textually.
The identification of the use of this software must appear within the digital works in a manner that is visible to the end user and upon any physical packaging.
The software may not be reverse engineered or modified without prior written consent of the author(s).
No source code forming any part of The Software is to be distributed without explicit written permission from the author(s).

Features

Entirely GPU based core written in assembler.
Kudos Ware Licensing model
Text functions
Up to 512 independent, fully programmable Objects with 16.16 sub-pixel positioning
Animation Engine complete with scaling and mirroring functions
Full control over Objects using a HAL
Human Readable object composition lists
Dynamic Branching Object Support
Dynamic Object Culling
Dynamic Object Redefinition
CLUT/RGB/CRY support
Collision handling via single or multiple bounding boxes per object
Particle functions
MemoryTrack load/save and buit-in high score management
Teamtap support
Tile Map Engine (with 16.16 sub-pixel accuracy)
BLiTTER support with a fast software-buffered GPU pipeline.
Integrated on screen dubugging.

Credits

Code and Documentation: Cyrano Jones
U-235 Audio Engine: Linkovitch
ZeroPlayer Audio Engine: ZeroSquare
LSPlayer by Arnaud Carre, Jaguar port by EricDe45
JaguarGD code provided by SainT / RetroHQ
Logo and Artwork: Sonik

Greetings and Thanks

In no special order:

U-235 / ZeroSquare / Arnaud Carre / EricDe45 for providing the audio engines which can be interfaced with this library.
Jagware - Special thanks to SCPCD, ZeroSquare (Also for the revised 2k EEPROM code) for the development and debugging assistance, to Matmook for developing this further and to GT-Turbo for his enthusiasm.
Shamus and the VirtualJaguar team for a fantastic emulator that just keeps on giving. Here’s to continuing to provide bug reports and getting fixes in the future!
Sinister Developments for the basis of the Object Creation routines.

RAPTOR Functions, Equates and Variables

All RAPTOR functions, equates and variables are listed in the RAPTOR.INC file, which should be included in all your RAPTOR applications.
The EQUATES contain human readable values designed to make writing (and later, reading) your source code easier.
All RAPTOR functions start with RAPTOR_ these will be detailed on the following pages.
All RAPTOR variables start with raptor_ so that they can be distinguished from functions.
The .INC file can be found in RAPTOR\INCS.

RAPTOR Application Files

RAPTOR applications consist of the following files:

_RAPAPP.S	Your code will go into this file
_RAPINIT.S	Script file defining the composition of all display objects and lists
_RAPPIXL.S	Script file defining particle effect parameters
RAPTOR.O	The RAPTOR Library Object File
RAPTOR235.O	The RAPTOR U235SE Interface Library (Optional)
RAPTORMT.O	The RAPTOR MemoryTrack Interface Library (Optional)
EXTERNAL FILES	External data files, eg, music Module, Audio files, Graphics
DSP.O	The U235 Sound Engine Object File (Optional)
_RAPU235.S	Script file defining U235 Sound Effects (Optional)

These files will be explored in the Examples Documentation.

RAPTOR.O Function Calls

This section will describe all the function calls, along with their expected input parameters and their outputs. Example code will be provided in the Examples section found later in the manual.

RAPTOR_HWinit

This function is called at the start of every RAPTOR application. It will configure the system to the specified video mode, install the RAPTOR Core to the GPU local memory, create the initial database of objects from the _RAPINIT.S file, initialize and clear the Particle system and return the system in a usable state, ready for applications to run.

Expected Inputs:

raptor_vidmode	Video mode – CRY16, RGB16, RGB24, DIRECT16
raptor_videnable	Video Enable Mask
raptor_varmod	VARMOD On or Off
raptor_partbuf_x	Width of Particle & Text window in pixels
raptor_partbuf_y	Height of Particle& Text window in pixels
raptor_top_of_bss	Start of the BSS section in the binary
raptor_trashram	Start of work RAM (end of the BSS section)
raptor_MTwork	16k workspace for the MemoryTrack module (If the MemoryTrack module is used, else can point to anything, and the 16k need not be reserved)
raptor_uvbi_jump	Address of the user VBI hook
raptor_poobjl	Address of the Pre Object List hook
raptor_probjl	Address of the Post Object List hook
raptor_8x8_addr	Address of the 8x8 font data
raptor_8x16_addr	Address of the 8x16 font data
raptor_16x16_addr	Address of the 16x16 font data
raptor_partipal	Address of the BMP file containing the font/particle palette data
raptor_pgfx	Address of the Particle & Text window bitmap
raptor_pgfxe	End address of the Particle & Text window bitmap
raptor_spritetab	Address of the RAPTOR Object data table
raptor_mtapp	Pointer to the MemoryTrack Application Name (If the MemoryTrack module is used, else can point to anything)
raptor_mtfn	Pointer to the MemoryTrack File Name (If the MemoryTrack module is used, else can point to anything)
raptor_inittab	Pointer to the data in the _RAPINIT.S file

If using the U235 engine, the following input is also expected:

raptor_samplebank_ptr

Pointer to the data in the _RAPU235.S file

If using the Tile Map functions, the following inputs are also expected:

raptor_maptop_obj	RAPTOR Object index for the first object in the map
raptor_tiles_x	Width in pixels of a single map tile
raptor_tiles_y	Height in pixels of s single map tile
raptor_tilesperx	Number of horizontal tiles to draw on screen
raptor_tilespery	Number of vertical tiles to draw on screen
raptor_mapwidth	Width (in tiles) of the map data
raptor_mapheight	Height (in tiles) of the map data
raptor_tilerem_mask	Mask for calculating position (tile width -1)
raptor_mapbmptiles	Pointer to the tile bitmap data
raptor_map_tiles_bits	Bit depth of the tileset used (1,2,4,8,16) If this is not set, 4bpp is assumed for backwards compatibility

Outputs: None

RAPTOR_start_video

This function starts video generation. Before this function is called the screen will remain blank.

Expected Inputs: None
Outputs: None

RAPTOR_setlist

This function selects a RAPTOR list to be displayed. The lists are defined in the _RAPINIT.S file and will be described later in the manual.

Expected inputs:

D0	List number to display

Outputs: None

RAPTOR_particle_init

This function initializes the Particle Engine, which is also used for Text Output.

It will configure the Particle Table database and clear the bitmap used for rendering particles and text. The particle and text bitmap will always use CLUT 15 (colours 240-256) in the 256 colour palette.

Its colour palette is defined in the Windows BMP file partipal.bmp, and the font data is defined in the three font files in the FONTS folder, F_8x8.BMP, F_8x16.BMP and F_16x16.BMP.

Different fonts for each size can be stacked vertically below each other in the bitmap files, as can be seen if they are opened in a picture viewer.

Expected inputs: None
Outputs: None

RAPTOR_particle_clear

This function will clear the particle and text layer bitmap.

Expected inputs: None
Outputs: None

RAPTOR_use8x8fontpal

Apply the palette from the 8x8 font bitmap to a specified CLUT.

Expected inputs:

D0	CLUT to put the font palette data into (0-15)

Outputs: None

RAPTOR_use8x16fontpal

Apply the palette from the 8x16 font bitmap to a specified CLUT.

Expected inputs:

D0	CLUT to put the font palette data into (0-15)

Outputs: None

RAPTOR_use16x16fontpal

Apply the palette from the 16x16 font bitmap to a specified CLUT.

Expected inputs:

D0	CLUT to put the font palette data into (0-15)

Outputs: None

RAPTOR_usepartipal

Apply the palette from the partipal bitmap to a specified CLUT.

Expected inputs:

D0	CLUT to put the font palette data into (0-15)

Outputs: None

RAPTOR_print

This function allows text to be sent to the display window. Text can be one of three font sizes, and can use any number of fonts as defined in the font Windows BMP files. All fonts must use the same palette as defined in the partipal.bmp file.

Expected inputs:

A0	Pointer to the text string
D0	X position to print (Note: will be rounded to an even value)
D1	Y position to print
D2	Font size (0=8x8, 1=8x16, 2=16x16)
D3	Font index (0=1st font in BMP, 1=2nd, etc.)

Outputs: None

RAPTOR_printr

Resumes printing from the previous position.

Expected inputs:

A0	Pointer to the text string

Print Commands

The print string can contain additional commands beyond character graphics to manipulate the output string.

raptor_t_quit	Used to terminate the string
raptor_t_lf	Used to issue a line feed
raptor_t_font_idx	Used to change the font index
raptor_t_font_siz	Used to change the font size
raptor_t_pos_xy	Used to re-position the print location in the text (particle) layer
raptor_t_home	Used to home the cursor to the top left
raptor_t_right	Used to subspace offset the text

RAPTOR_GFXConvert

This function will convert the specified image (Windows BMP 4/8/16/24 bpp or TGA 16/24 bpp) to Jaguar Bitmap format.

Expected inputs:

A0	Pointer to image to convert
A1	Workspace RAM to use for conversion

Outputs: None

RAPTOR_move_palette

This function will move the palette from the last converted image to the specified location.

Expected inputs:

A1	Address to copy palette data to

Outputs: None

RAPTOR_fade_clut

This function will fade the selected entries in the CLUT into another set of colours. It will work with the full 256c CLUT, or individual sub-CLUTS, or specifically targeted indexes only.

NOTE: raptor_fade_delay (.w) contains the number of frames to wait before changing any values.

Expected inputs:

D0	CLUT to use 0-15, set to 0 select the full 256c CLUT
D7	Number of colours to fade (set 16 for full sub-CLUT)
A1	Pointer to new palette data

Outputs:

D0	D0 is set to negative if any of the selected indexes changed. Used to detect when palettes match.

RAPTOR_fade_clutindex

This function will fade a specific single CLUT index into another one.

NOTE: raptor_fade_delay (.w) contains the number of frames to wait before changing any values.

Expected inputs:

D0	Clut index to fade (0-255)
D1	New 16 bit colour value to fade towards

Outputs:

D0	D0 is set to negative if the background colour changed. Used to detect when palettes match.

RAPTOR_UPDATE_ALL

This function will update all the RAPTOR and Particle objects with any changes made to their database fields.

Expected inputs: None
Outputs: None

RAPTOR_wait_frame

This function will halt the running application and wait until the vertical sync.

Expected inputs: None
Outputs: None

RAPTOR_wait_frame_UPDATE_ALL

This function will halt the running application and wait until the vertical sync, and then update all RAPTOR and Particle objects.

Expected inputs: None
Outputs: None

RAPTOR_update_offscreenlist

This function will update a given RAPTOR list, regardless of if it is the currently displayed list or not. This is useful for populating another list prior to displaying it, and thus preventing a single screen of stale data displaying following the switch.

Expected inputs:

D0	RAPTOR list to update

Outputs: None

RAPTOR_UPDATE_SPRITES

This function will force an update of all RAPTOR objects.

Expected inputs: None
Outputs: None

RAPTOR_UPDATE_PARTICLES

This function will force an update of all Particle objects.

Expected inputs: None
Outputs: None

RAPTOR_UPDATE_PARTICLES_ERASE

This function will force an erase of all Particle objects.

Expected inputs: None
Outputs: None

RAPTOR_UPDATE_PARTICLES_PLOT

This function will force plot-only of all Particle objects.

Expected inputs: None
Outputs: None

RAPTOR_call_GPU_code

This function will set the GPU PC to the specified address and start it running. The 68000 will be placed into a tight loop until the GPU is halted.

Expected inputs:

A0	Address to set the GPU PC

Outputs: None

RAPTOR_call_GPU_code_STOP

This function will set the GPU PC to the specified address and start it running, and then HALT the 68000 until the next VBI occurs via STOP command. You must ensure that the GPU is not used during the VB Interrupt or that the code will complete before a VB is triggered.

Expected inputs:

A0	Address to set the GPU PC

Outputs: None

RAPTOR_call_GPU_code_nowait

This function will set the GPU PC to the specified address and start it running, and then immediately continue execution on the 68000.

Expected inputs:

A0	Address to set the GPU PC

Outputs: None

RAPTOR_GPU_COLLISION

This function will call the RAPTOR collision module. It will perform hit point/damage on all colliding RAPTOR object(s) and flag a global ‘collision occurred’ variable, and will also tag each colliding object.

Expected inputs:

raptor_sourcel	RAPTOR Object index value for source range (low)
raptor_sourceh	RAPTOR Object index value for source range (high)
raptor_targetl	RAPTOR Object index value for target range (low)
raptor_targeth	RAPTOR Object index value for source range (high)

Outputs:

raptor_result	Global flag indicating at least one collision occurred
raptor_collisionlist	This table is appended with the address of the raptor object that was hit, followed by the address of the object that caused the collision

This function will compare all objects between raptor_sourcel and raptor_sourceh against all objects between raptor_targetl and raptor_targeth.

If any of the objects have their cant_hit flag set they will be skipped.

If a collision occurs (defined by the target box values in the object definition list) the damage value of the source is subtracted from the hitpoint value of the target, and the sprite_was_hit flag is set in the target object.

If the target hitpoints go negative the object will obay it’s keep or remove definition.

The sprite_was_hit flag needs to be reset before another collision test occurs.

RAPTOR_GPU_COLLISION_USERTABLE

Same as the above function, except you can specify where the collision table results will be stored in RAM.

As above with the exception that the location for the usertable is stored in: raptor_col_user

NOTE: It is the user's responsibility to ensure there is enough buffer space for to results.

RAPTOR_obj_shift

This function will update the x and y values of a given range of objects by set values. It is useful of moving a large number of objects at the same time.

Expected inputs:

d0	Value to add to sprite_x for each object in 16.16 format
d1	Value to add to sprite_y for each object in 16.16 format
d2	Number of objects to change
a0	Address of start object in sprite_table

Outputs: None

RAPTOR_objsort

This function will sort a specified list of RAPTOR objects by a given field, either highest to lowest or lowest to highest order, prioritising them for display order. This is useful in order to, for example, depth sort sprites vertically with the lowest Y-value at the front of the display.

NOTE: This function call directly modifies the live display list data and must be called after any RAPTOR_UPDATE call, as they will re-create the linear order of the list.

Expected inputs:

a0	Start object base addr in sprite_table
d0	field to sort by (sprite_y, sprite_x, etc)
d1	Number of objects to sort
d2	Direction of sort: 1: Highest at front -1: Lowest at front)

Outputs: None

RAPTOR_HEX_to_DEC

This function will convert a hexadecimal value into ASCII decimal.

Expected inputs:

D1	Hexadecimal value to convert
D4	Number of digits in the output string -1
A0	Address to store the converted string

Outputs:

(A0)	String of characters (D4 long) with converted number

RAPTOR_HEXtoASCII

This function will convert a hexadecimal value into ASCII decimal.

Expected inputs:

A0	Pointer to Hexadecimal value
A1	Pointer to Output Buffer (2 bytes ASCII for each byte of hex)
D0	Bytes to convert-1

Outputs:

(A1)	String of characters (D0*2 long) with converted number

RAPTOR_calc_angle

This function will return the angle (in the 512 angle format used by the internal trigtable) between two sets of co-ordinates (x1,y1) and (x2,y2)

In order to use this call you must first call RAPTOR_init_calc_angle with D0 pointing to a buffer of 65540 bytes. The init function will generate a required table at this location.

NOTE: only pass the integer componants of the co-ordinates to the function.

Expected inputs:

d0	x1 (function moves this to raptor_gpu_x1)
d1	y1 (function moves this to raptor_gpu_y1)
d2	x2 (function moves this to raptor_gpu_x2)
d3	y2 (function moves this to raptor_gpu_y2)

Outputs:

d0	Angle between points (0-511)

RAPTOR_particle_injection_GPU

This function will update the particle database with the specified particle effect pattern.

Expected inputs:

raptor_part_inject_addr

Pointer to the particle effect structure to inject

Outputs: None

Particle Effect Structure

The structure(s) for the particle effects are located in the _RAPPIXL.S file, and are defined as below:

X	X position to start the effect
Y	Y position to start the effect
Pixel Count	Number of pixels in the effect

This is immediately followed by a list of pixel definitions, one for each specified by Pixel count above.

Angle	Angle particle will move at (0-511) Note: zero is EAST, 128 is SOUTH, 256 is WEST and 384=NORTH
Speed	The speed the particle will travel along the specified angle
Angular velocity	The rate of turn applied each update. Positive numbers will rotate clockwise, negative will rotate anti-clockwise
Initial colour	The initial colour (0-15) for the pixel. The palette used is specified in the PARTIPAL.BMP file, and is the same used for the fonts
Colour decay rate	Frame delay between each colour step downwards
Pixel life	How long the pixel will remain active (in frames)

Note: there are two global particle variables:

raptor_pdriftx	16.16 x-value to add to all particles next update
raptor_drifty	16.16 y-value to add to all particles next update

RAPTOR_chk_highscores

This function compares a specified high score against one of the top ten lists.

Expected inputs:

D0	Score to test
D1	Score table to use (0-4)
A0	Pointer to 8 character name to inject

Outputs:

D0	Result: Negative = score not in top 10 Positive = score is a new top 10 entry

If the result is positive, the RAPTOR_resort_score_table function must be called.
RAPTOR supports 5 top ten lists, storing both a 32-bit score and an 8 character name for each entry in each table.

RAPTOR_resort_score_table

This function will re-sort the specified score table.

Expected inputs:

A0	Pointer to 8 character name to enter into the table.
D1	Score table to use (0-4)

Outputs: None

RAPTOR_init_map_objs

This function configures the Tile Map system. It requires the variables for the Tile Map engine to be configured before RAPTOR_HWinit.

It also requires that a special structure layout is present in _RAPINIT.S – which will be described in the Examples documentation (EX-10)

Expected inputs:

raptor_mapindex	Pointer to the map data
raptor_maptop_obj	Pointer to the first object in the map define
raptor_map_position_x	16.16 map co-ordinate (x)
raptor_map_position_y	16.16 map co-ordinate (y)
raptor_gmap_startx	32 bit screen position (in pixels) for where the left edge of the map will be drawn
raptor_gmap_starty	32 bit screen position (in pixels) for where the top edge of the map will be drawn

Outputs: None

RAPTOR_map_set_position

This function sets the X and Y co-ordinates (in pixels and sub-pixels) for the top-left of the map to be displayed on the screen.

Expected inputs:

raptor_map_position_x	16.16 map co-ordinate (x)
raptor_map_position_y	16.16 map co-ordinate (y)

Outputs: None

RAPTOR_d_lz77

This function decompresses LZ77 compressed data using the 68000.

Expected inputs:

A0	Pointer to compressed data
A1	Address to decompress data into

Outputs: None

RAPTOR_NRVUnpack

This function decompresses NRV2e compressed data using the GPU. It requires exclusive use of the GPU - VBI updating MUST be disabled. A file compressed using NRV2e cannot spam the ROM addresses at the 4mb boundary.

Expected inputs:

A0	Pointer to compressed data
A1	Address to decompress data into

Outputs: None

RAPTOR_ShrinklerDecompress

From the Shrinkler documentation:

; Copyright 1999-2015 Aske Simon Christensen.
;
; The code herein is free to use, in whole or in part, modified or as is, for any legal purpose.
; No warranties of any kind are given as to its behavior or suitability.
; Decompress Shrinkler-compressed data produced with the --data option.
;
; A0 = Compressed data
; A1 = Decompressed data destination
; A2 = Progress callback, can be zero if no callback is desired.
;      Callback will be called continuously with
;      D0 = Number of bytes decompressed so far
;      A0 = Callback argument
; A3 = Callback argument
;
; Uses 3 kilobytes of space on the stack.
; Preserves D2-D7/A2-A6 and assumes callback does the same.
;
; Decompression code may read one longword beyond compressed data.
; The contents of this longword does not matter.

RAPTOR_PackFireDecompress

From the PackFire documentation:

; ------------------------------------------
; packed data in a0
; dest in a1
; probs buffer in a2 (must be 15980 bytes)

RAPTOR_PackFire_TinyDecompress

From the PackFireTiny documentation:

; ------------------------------------------
; packed data in a0
; dest in a1

RAPTOR_setclock

This function sets the 3-digit RAPTOR clock to the value in D0. It will also update the hex and ascii values for the clock as required.

Expected Inputs:

D0	New value for the clock (0-999)

Outputs: None

The clock functions are controlled via the following variables:

raptor_clock_mode	Clock operation mode - set to: raptor_clock_freeze: stops the clock raptor_clock_cdown: clock will count down to 0 and stop raptor_clock_cup: clock will count up to 999 and stop
raptor_clock_jiffies	Current number of frames this clock tick (can be used to calculate subsecond values
raptor_clock_hex	Hexadecimal value of the clock (0-999)
raptor_clock_val	ASCII value of the clock, zero terminated, ready to print.

Outputs: None

RAPTOR_addclock

This function will add x seconds to the clock value, and also update the raptor_clock_hex and raptor_clock_val accordingly.

Expected Inputs:

D0	Number of seconds to add

Outputs: None

RAPTOR_subclock

This function will subtract x seconds from the clock value, and also update the raptor_clock_hex and raptor_clock_val accordingly.

D0	Number of seconds to subtract

Outputs: None

RAPTOR_ERROR

This function will effectively halt the application and flash the background colour. It will never return. It is useful for debugging.

Expected inputs: None
Outputs: None

RAPTOR_Version

This function will return a pointer to a string containing the RAPTOR version number.

Expected inputs: None

Outputs:

A0	Pointer to string containing version number

RAPTOR_blitter

This function will call the BLiTER to process a pre-defined list of BLiTTER commands.

Expected inputs:

raptor_blitlist_ptr

Pointer to a table of BLiTTER commands as defined below.

Note: The table *MUST* be .long aligned

Outputs: None

Table definition:

A1_Base	Longword containing value for A1_Base register
A1_Flags	Longword containing value for A1_Flags register
A1_Clip	Longword containing value for A1_Clip register
A1_Pixel	Longword containing value for A1_Pixel register
A1_Step_Int	Longword containing value for A1_Step_Int register
A1_Step_Fract	Longword containing value for A1_Step_Fract register
A1_Pixel_pointer	Longword containing value for A1_Pixel_Pointer register
A1_Inc_Int	Longword containing value for A1_Inc_Int register
A1_Inc_Fract	Longword containing value for A1_Inc_Fract register
A2_Base	Longword containing value for A2_Base register
A2_Flags	Longword containing value for A2_Flags register
B_PatD	Longword containing value for B_PatD register
A2_Pixel	Longword containing value for A2_Pixel register
A2_Step	Longword containing value for A2_Step register
B_Counter	Longword containing value for B_Counter register
B_CMD	Longword containing value for B_CMD register

The table is terminated by a row of data containing -1 in the A1_Base field.

RAPTOR_random

32-Bit pseudo-random number generator.

Expected inputs: None

Outputs:

D0	32 Bit random number

RAPTOR_eeReadLongWord

Read a 32-Bit value from the EEPROM chip

Note: 2k only - will NOT work for 128 byte EEPROMS
The EEPROM addressing is 16 bits, so addresses 0-1023 contain 2048 bytes of data (16 bits per address)

Expected Inputs:

D1	Address to read from (16 bit addressing)

Outputs:

D0	32 bit value at address

RAPTOR_eeWriteLongWord

Write a 32-Bit value to the EEPROM chip

Note: 2k only - will NOT work for 128 byte EEPROMS
The EEPROM addressing is 16 bits, so addresses 0-1023 contain 2048 bytes of data (16 bits per address)

Expected Inputs:

D0	32 bit value to write
D1	Address to write at (16 bit addressing)

RAPTOR_eeReadWord

Read a 16-Bit value from the EEPROM chip

Note: 2k only - will NOT work for 128 byte EEPROMS
The EEPROM addressing is 16 bits, so addresses 0-1023 contain 2048 bytes of data (16 bits per address)

Expected Inputs:

D1	Address to read from (16 bit addressing)

Outputs:

D0	16 bit value at address

RAPTOR_eeWriteWord

Write a 16-Bit value to the EEPROM chip

Note: 2k only - will NOT work for 128 byte EEPROMS
The EEPROM addressing is 16 bits, so addresses 0-1023 contain 2048 bytes of data (16 bits per address)

Expected Inputs:

D0	16 bit value to write
D1	Address to write at (16 bit addressing)

Outputs:

D0	Non Zero result indicates error

RAPTOR_eeReadBank

Read the entire 2k of EEPROM data to memory.

Note: This function can take several seconds.

Expected Inputs:

A0	Address to read bank into (2048 bytes)

Outputs:

D0	Non Zero result indicates error

RAPTOR_eeWriteBank

Write the entire 2k of EEPROM data from memory.

Note: This function can take several seconds.

Expected Inputs:

A0	Address to write bank from (2048 bytes)

Outputs:

D0	Non Zero result indicates error

RAPTOR_eeUpdateChecksum

Read the entire 2k of EEPROM data, calculate a new checksum, and write it.

Expected Inputs: NONE

Outputs:

D0	Non Zero result indicates error

RAPTOR_eeValidateChecksum

Read the entire 2k of EEPROM data and validate the checksum.

Expected Inputs: NONE

Outputs:

D0	Non Zero result indicates error

Teamtap Functions

Many thanks to Matthias Domin for the example code used as a basis for these routines.

RAPTOR_check_left_teamptap

Checks if the left teamtap is connected

Expected Inputs: NONE

Outputs:

D0	negative - no teamtap positive - teamtap detected

RAPTOR_check_right_teamptap

Checks if the right teamtap is connected

Expected Inputs: NONE

Outputs:

D0	negative - no teamtap positive - teamtap detected

RAPTOR_read_left_teamtap_state

Polls all four ports in the left teamtap.

Expected Inputs: NONE
Outputs: NONE

RAPTOR_read_right_teamtap_state

Polls all four ports in theright teamtap.

Expected Inputs: NONE
Outputs: NONE

RAPTOR_read_left_teamtap_pad

This function will return the button state for a specified pad in the left teamtap.

Expected inputs:

D0	Port number to read (0-3)

Outputs:

D0	U235SE compatible bitmask for the specified pad

RAPTOR_read_right_teamtap_pad

This function will return the button state for a specified pad in the right teamtap.

Expected inputs:

D0	Port number to read (0-3)

Outputs:

D0	U235SE compatible bitmask for the specified pad

Exposed variables for the teamtap are:

raptor_left_teamtap	Connection status of left teamtap (-1 / 1)
raptor_right_teamtap	Connection status of right teamtap (-1 / 1)
raptor_left_teamtap_pad0	Last read status of left teamtap port 0 in U235SE format
raptor_left_teamtap_pad1	Last read status of left teamtap port 1 in U235SE format
raptor_left_teamtap_pad2	Last read status of left teamtap port 2 in U235SE format
raptor_left_teamtap_pad3	Last read status of left teamtap port 3 in U235SE format
raptor_right_teamtap_pad0	Last read status of right teamtap port 0 in U235SE format
raptor_right_teamtap_pad1	Last read status of right teamtap port 1 in U235SE format
raptor_right_teamtap_pad2	Last read status of right teamtap port 2 in U235SE format
raptor_right_teamtap_pad3	Last read status of right teamtap port 3 in U235SE format

Dynamic Objects

Dynamically redefining objects

API 2.0+ allows objects in your list to be dynamically changed during runtime by altering several of their attributes. These are listed below:

sprite_bdepth	Set the bit depth of the object (1,2,4,8,16)
sprite_cryrgb	Set the object to either CRY or RGB
sprite_trans	Set the transparency flag for the object
sprite_height	As defined in the _rapinit.s section
sprite_bytewid	As defined in the _rapinit.s section
sprite_gwidth	As defined in the _rapinit.s section

Note, after setting sprite_bytewid you must manually update sprite_width or collision and edge wrap will not work.

You can also tag additional data to a given object by using the sprite_userdat1, sprite_userdat2, sprite_userdat3 and sprite_userdat4 fields. Each field is a 32 bit value.
An additional field, sprite_indexnumber, is included to aid in function acceleration for JagStudio. It contains the object index number from the top of the table.

Dynamic Object Culling

A powerful new feature of API 2.0 is Dynamic Object Culling – this will automatically prevent any object(s) set to ‘is_inactive’ from the current list from the active Object List being processed by the Object Processor by way of modifying the previous active object's link pointer to skip the inactive objects.

It is important to note that the first and last objects in any list must be set to active at all times.

With this feature you are now able to create extremely long lists (up to 512 objects) and enable/disable specific ones at runtime without incurring any processing costs for the unused objects.

Non-RAPTOR Objects

This section will cover the hooks and function calls for creating and manipulating objects that are not managed by the RAPTOR Engine. These routines are based on the Sinister Developments Object Library.

RAPTOR_CreateObject

This function will create a new object in the Object list.

Expected inputs:

D0	Object type: 0 – Bitmap Object 1 – Scaled Bitmap Object 2 – GPU Object 3 – Branch Object 4 – Stop Object
D1	Height (in pixels) of Object
D2	Width (in bytes) of a single line of the image
D3	Colour depth 0 - 1bpp 1 - 2bpp 2 - 4bpp 3 - 8bpp 4 - 16bpp 5 - 24bpp
D4	Transparency 0 – Opaque 1 – Transparent
D5	Image Width (in bytes) of the rendered image
A0	Address of the object
A1	Pointer to the bitmap data

Outputs: None

RAPTOR_rmw

This function will convert the previous object made with RAPTOR_CreateObject into a CRY (Read/Modify/Write) Object.

Expected inputs: None
Outputs: None

RAPTOR_setpalt

This function will set the CLUT for the previous object made with RAPTOR_CreateObject.

Expected inputs:

D0	CLUT (0-15) to set

Outputs: None

RAPTOR_reflect

This function will set the MIRROR bit for the previous object made with RAPTOR_CreateObject – effectively flipping the bitmap horizontally.

Expected inputs: None
Outputs: None

RAPTOR_setup_object_xyg

This function will change the X, Y positions and Bitmap Address for a Non-RAPTOR Object.

Expected inputs:

A0	Pointer to a Non-RAPTOR Object
D0	New X-Position (Not Sub-Pixel)
D1	New Y-Position (Not Sub-Pixel)
D2	New Bitmap Address

Outputs: None

RAPTOR_setup_object_xg

This function will change the X position and Bitmap Address for a Non-RAPTOR Object.

Expected inputs:

A0	Pointer to a Non-RAPTOR Object
D0	New X-Position (Not Sub-Pixel)
D2	New Bitmap Address

Outputs: None

RAPTOR_setup_object_g

This function will change the Bitmap Address for a Non-RAPTOR Object.

Expected inputs:

A0	Pointer to a Non-RAPTOR Object
D2	New Bitmap Address

Outputs: None

RAPTOR_setup_object_xy

This function will change the X and Y position for a Non-RAPTOR Object.

Expected inputs:

A0	Pointer to a Non-RAPTOR Object
D0	New X-Position (Not Sub-Pixel)
D1	New Y-Position (Not Sub-Pixel)

Outputs: None

RAPTOR_setup_object_xyz

This function will change the X, Y and Scale Ratio for a Non-RAPTOR Object.

Expected inputs:

A0	Pointer to a Non-RAPTOR Object
D0	New X-Position (Not Sub-Pixel)
D1	New Y-Position (Not Sub-Pixel)
D3	Horizontal Scale value
D4	Vertical Scale value

Outputs: None

RAPTOR_setup_object_bra

This function will insert abranch object into the list, defined as below.

Expected inputs:

D0	Object number in list to edit (starts at 0)
D1	Branch type: 0 = Less 1 = More 2 = Always
D2	YPOS to test on
D3	Object number to branch to if branch taken

Outputs: None

RAPTOR_attach_rmotion

This functin will attach an rMotion script to a RAPTOR object.

Expected inputs:

A0	Pointer to a RAPTOR object
A1	Pointer to an rMotion script

Outputs: None

RAPTOR_user_vbi (System Hook)

This routine exists in the application code written by the user. It is called by the RAPTOR core every VBI, and allows the user to synchronise code under interrupt.

No registers are saved or restored around this function. It is the user’s responsibility to manage this.
Exiting the user routine is via an RTS command.
If this hook is not required it must point to an RTS.

RAPTOR Initialization File (_RAPINIT.S)

This file contains the human readable scripts (RAPTOR Lists) used to generate the visible screens generated by RAPTOR Engine. It also contains the MemoryTrack Application and Filenames.

The file is defined as below:

MemoryTrack configuration Info	Application and Filename used by MemoryTrack routines
>RAPTOR<	Denotes the start of the RAPTOR data
LIST	Denotes the start of a RAPTOR list
List Data	Per-object data for the items in the list
STOP	Denotes the end of a RAPTOR list
<RAPTOR>	Denotes the end of the RAPTOR data

RAPTOR List Data

This file contains the human readable definitions for the Objects used to generate a ‘scene’

The LIST is defined as below:

REPEAT COUNTER	Create this many objects of this type (or 1 for a single object)
sprite_active	Active / Inactive flag
sprite_x	Object X co-ordinate in 16.16 format
sprite_y	Object Y co-ordinate in 16.16 format
sprite_xadd	Value to auto-add each call to sprite_x
sprite_yadd	Value to auto-add each call to sprite_y
sprite_width	Width of Object (in pixels)
sprite_height	Height of Object (in pixels)
sprite_flip	Flag for horizontally flipping in the image data
sprite_coffx	X offset from center for collision box center
sprite_coffy	Y offset from center for collision box center
sprite_hbox	Width of collision box
sprite_vbox	Height of collision box
sprite_gfxbase	Pointer to bitmap data
BIT_DEPTH	Bitmap depth (1/2/4/8/16/24)
CRY / RGB	Bitmap graphics type
TRANSPARENCY	Object transparency flag
sprite_framesz	Size (in bytes) of a single frame of sprite data
sprite_bytewid	Size (in bytes) of a single horizontal line of sprite data
sprite_animspd	Frame delay between animation changes
sprite_maxframe	Number of frames in animation chain
sprite_animloop	Play once / Repeat flag for animation chain
sprite_wrap	Flag for screen edge wrap, remove or ignore
sprite_timer	Frames sprite is active for (or -1 for infinite)
sprite_track	Flag for 16.16 updates, or pointer to an x/y table
sprite_tracktop	Loop point in x/y table (if used)
sprite_scaled	Flag for if Object is scaled or unscaled
sprite_scale_x	Horizontal scale factor
sprite_scale_y	Vertical scale factor
sprite_was_hit	Collision flag
sprite_CLUT	CLUT Index value
sprite_colchk	Flag defining if Object can collide with another
sprite_remhit	Flag to define if sprite is removed on collision or not
sprite_bboxlink	Flag for single bounding box, or pointer to box datalist*
sprite_hitpoint	Hitpoints for this Object
sprite_damage	Hitpoints deducted from colliding object
sprite_gwidth	Object bitmap width of data (in bytes)

*Multiple Bounding Box List

Multiple bounding box collision lists are defined as below

Number of Boxes	Number of bounding boxes for this Object
X-offs	x-offset from the middle of the object for current box
Y-offs	y-offset from the middle of the object for current box
Width	Bounding box width /2
Height	Bounding box height /2

Hooks to internal registers, counters and flags

The following variables are exposed to allow some direct access into the internal functionality of RAPTOR.

raptor_top_of_bss	.L Points to the end of the BSS section
raptor_ticks	.W increments every frame
raptor_vbl_time_remain	.L returns a value from wait_frame to determine free CPU time per frame
raptor_ntsc_flag	.W negative for NTSC, positive for PAL
raptor_blitter_use	.L RAPTOR BLiTER use flag: 0 – Automatic -1 – Never use BLiTTER 1 – Use BLiTTER Note: All the RAPTOR API BLiTTER calls temporarily disable RAPTOR from using the BLiTTER while running.
raptor_font8x8_pal	.W *16 – The palette data for the 8x8 font (Should be the same for all fonts)
raptor_font8x16_pal	.W *16 – The palette data for the 8x16 font (Should be the same for all fonts)
raptor_font16x16_pal	.W *16 – The palette data for the 16x16 font (Should be the same for all fonts)
raptor_highscoresX_hex	Points to 10 longwords containing the score for table X (x can be 1 to 5)
raptor_highscoresX_nam	Points to a table containing the names for table X (x can be 1 to 5) – The names are 8 bytes each.
raptor_user_savedata	Points to 512 bytes that can be used to save data to MemoryTrack.
RAPTOR_particle_gfxbase	Points to the base of the bitmap image for the text/particle layer.
RAPTOR_particle_trigtable	Points to the internal trig table, 512 sets of x/y 16.16 add values in longwords (8 bytes per 'degree')
raptor_collisionlist	The GPU Collision routine will fill this table each time it is called with a list of: .L Address of target object that was collided .L Address of souce object that caused the collision The list is terminated with a -1 in the target column.
RAPTOR_VB_INTERRUPT	Location of the LEVEL0 interrupt handler function inside RAPTOR.O
RAPTOR_VI	Calculated VI value for the LEVEL0 (RAPTOR_VB_INTERRUPT) to trigger on
raptor_last_score_hex	The last score entered into the scoreboard
raptor_last_score_name	The last name entered into the scoreboard
raptor_table_starts	pointer to the top of an array of longwords containing pointers to the first object in each defined LIST

RAPTOR Debug Console

RAPTOR API features a powerful console that is completely independant of the user defined RAPTOR objects in any list.

There is a slight performance impact when the Debug Console is enabled.

Debug Console Image

The console can be configured by the following longwords:

raptor_console_x	x position on screen. Not this is a 32-bit integer and not a 16.16 value.
raptor_console_y	y position on screen. Not this is a 32-bit integer and not a 16.16 value.
raptor_console_visible	If this longword is positive the console will be visible. If negative it is disabled
raptor_console_monitors	This is the start of an array of 16 longwords that the console will use to "peek" the values from. For convenience the upper 8 values are pre-loaded with: 08: Shows current raptor_ticks (.w) / NTSCflag (.w) 09: VBL Time Remain value 10: Collision result register 11: Currently active RAPTOR List 12: Tilemap X position 13: Tilemap Y position 14: End of program data 15: Free RAM available

RAPTOR_console_update_registers

This command will refresh the register dump on the console.

Expected inputs: None
Outputs: None

RAPTOR_console_update_usermonitors

This command will refresh the values in the user monitors on the console.

Expected inputs: None
Outputs: None

RAPTOR_console_update_textline

This command will update the text line on the console with a supplied string.

Expected inputs:

A0	0 or negative terminated string. Anything beyond 77 characters will be truncated.

Outputs: None

RAPTOR_console_inverse

This command will invert the console display (white/black or black/white)

Expected inputs: None
Outputs: None

RAPTORMT.O Function Calls

RAPTOR_mt_init

This function will initialize the MemoryTrack BIOS if a MemoryTrack cartridge is detected.

Expected Inputs: None
Outputs: None

RAPTOR_mt_save

This function will save the top 10 table to the MemoryTrack using the application name and filename specified in _RAPINIT.S. If no MemoryTrack is present, the function will exit cleanly.

Expected inputs: None
Outputs: None

Note: RAPTOR will use the following variables for saving, which are auto-loaded with a pointer to the high score data and its length during RAPTOR_mt_init.

RAPTOR_MT_start_address	Memory address to save from
RAPTOR_MT_save_length	Number of bytes to save

RAPTOR_mt_load

This function will load data from the MemoryTrack into main RAM.

The RAPTOR_mt_init function will auto-load the high score table if the MemoryTrack is present and the specified application name and file name exist.

Expected inputs:

RAPTOR_MT_start_address	Memory address to load into
RAPTOR_MT_save_length	Number of bytes to load

Outputs: None

RAPTOR235.O Function Calls

RAPTOR_U235init

This function will install and start the U235 Sound Engine, which is an optional module for both audio generation and jagpad reading. If this module is not used and these functions are required you can substitute another DSP engine, eg ZeroPlayer, instead. RAPTOR does not make any direct use of the DSP and leaves this available to the discretionof the programmer.

Expected inputs:

D0	Call with #U235SE_12KHZ, etc
D1	Call with #U235SE_12KHZ_PERIOD, etc

Outputs: None

RAPTOR_U235stopDSP

This function halts the DSP cleanly.

RAPTOR_U235playsample

This function will play the specified sound effect immediately using the U235 Sound Engine.

Expected inputs:

D1	((frequency/2)<<16)+(sample number<<8)+(Channel number<<4)+2 - see the U235SE documentation for more info

Outputs: None

RAPTOR_U235setmodule

This function will call the U235 Sound Engine to set a module to play. It will not actually start the module.

Expected inputs:

A0	Pointer to the module to play

RAPTOR_U235gomodule_mono

This function will start the specified module playing in mono mode. Playback is at the specified frequency set during RAPTOR_U235init, or at the last set by RAPTOR_U235ChangeReplayFrq.

Expected inputs: None
Outputs: None

RAPTOR_U235gomodule_stereo

This function will start the specified module playing in stereo mode. Playback is at the specified frequency set during RAPTOR_U235init, or at the last set by RAPTOR_U235ChangeReplayFrq.

Expected inputs: None
Outputs: None

RAPTOR_U235stopmodule

This function will halt any currently playing module and silence the audio channels used for music.

Expected inputs: None
Outputs: None

RAPTOR_U235queuesample

This function will queue the specified sound effect for the U235 Sound Engine.

Expected inputs:

D1	((frequency/2)<<16)+(sample number<<8)+(Channel number<<4)+2 - see the U235SE documentation for more info

Outputs: None

RAPTOR_U235playqueue

This command will play all queued samples.

Expected inputs: None
Outputs: None

RAPTOR_U235resetqueue

This command will reset the sample queue and clear all entries.

Expected inputs: None
Outputs: None

RAPTOR_U235setpad1

This function will set the U235SE to read PAD 1 as a JagPad.

Expected inputs: None
Outputs: None

RAPTOR_U235setrot1

This function will change the U235 SE rotary settings for the rotary in port 1.

Expected inputs:

D0	Interval (Scan interval)
D1	Delta (Steps to turn)

Outputs: None

RAPTOR_U235setpad2

This function will set the U235SE to read PAD 2 as a JagPad.

Expected inputs: None
Outputs: None

RAPTOR_U235setrot2

This function will change the U235 SE rotary settings for the rotary in port 2.

Expected inputs:

D0	Interval (Scan interval)
D1	Delta (Steps to turn)

Outputs: None

RAPTOR_U235SilenceChannels

This functions silences all the channels currently playing.

Expected input: None
Outputs: None

RAPTOR_U235ChangeReplayFrq

This function will change the replay frequence of modules.

Expected inputs:

D0	Call with #U235SE_12KHZ, etc
D1	Call with #U235SE_12KHZ_PERIOD, etc

Outputs: None

RAPTORGD.O Function Calls

The GameDrive module has its own datablock where functions will return details about the specific file/folder that is being accessed.
This is defined as below

raptor_GD_SERIAL	32-bit serial number
raptor_GD_ASERIAL	32-bit serial number in ASCII
raptor_SD_SERIAL	32-bit serial number
raptor_GD_LEDstate	16-bit LED stage flag
raptor_GD_cardstat	16-bit SD Card Inserted Status

There is also a file info block:

raptor_fileinfo:

raptor_fsize	32-bit size of file
raptor_fdate	16-bit date stamp
raptor_ftime	16-bit time stamp
raptor_fattr	8-bit file attribute flags bits are: AM_RDO - Read Only AM_HID - Hidden AM_SYS - System File AM_VOL - Volume Label AM_DIR - Directory AM_ARC - Archive AM_MASK can be used to clear as required
raptor_fshort	Short filename
raptor_flong	Long filename

RAPTOR_GD_Init

This function will install and start the RetroHQ Jaguar GameDrive module, which is an optional module for accessing many useful functions provided by this device from within your own applications.

Expected input: None
Outputs: None

RAPTOR_GD_BIOSVersion

This will return the GameDrive BIOS Version number.

Expected Inputs: None

Outputs:

D0	nn.nn BCD format, high word FIRMWARE, low word ASIC

RAPTOR_GD_ROMWriteEnable

This will enable write access to the ROM address space ($800000-$bfffff).

Expected Inputs:

D0	GD_ROMWRITE_ENABLE GD_ROMWRITE_DISABLE

Outputs: None

RAPTOR_GD_GetCartSerial

This will return the GameDrive serial number. This is unique per GD.

Expected Inputs: None

Outputs:

D0	Status result: 0: GD string is value !0: GD serial unable to be read
raptor_GD_SERIAL	This will be filled with the serial number

RAPTOR_GD_GetCardSerial

This will return the serial number of the mSD in the GameDrive. This is unique per mSD card.

Expected Inputs: None

Outputs:

D0	Status result: 0: GD string is value !0: GD serial unable to be read
raptor_SD_SERIAL	This will be filled with the serial number

RAPTOR_GD_CardIn

This will return the status of the mSD card slot in the GameDrive.

Expected Inputs: None

Outputs:

D0	Status result: 0: No SD card detected 1: SD card detected

RAPTOR_GD_Reset

This will reboot the GameDrive.

Expected Inputs: None
Outputs: None

RAPTOR_GD_SetLED

This will allow you to set the state of the LED on the GameDrive.

Expected Inputs:

D0	0: LED off 1: LED on

Outputs: None (But the LED will change on the GD!)

RAPTOR_GD_DebugString

Send a string to the gamedrive debug console.

Expected Inputs:

A0	Pointer to string to send

Outputs: None (But the string will be sent to the console!)

RAPTOR_GD_DirOpen

Opens a directory on the mSD card in the gamedrive to be used by other file system commands.

Expected Inputs:

A0	Pointer to path to open

Outputs:

D0	Status result: +ve: success - This is also the directory handle -ve: failure

RAPTOR_GD_DirRead

Reads the next entry in the directory structure.

Expected Inputs:

D0	Directory Handle

Outputs:

D0	Status result: +ve: success - Will update the raptor_fileinfo table -ve: failure

RAPTOR_GD_DirClose

Closes the directory structure.

Expected Inputs:

D0	Directory Handle

Outputs:

D0	Status result: +ve: success -ve: failure

RAPTOR_GD_FileOpen

Opens a file on the mSD card for I/O operations.

Expected Inputs:

D0	Mode: Values are as below GD_FOPEN_READ GD_FOPEN_WRITE GD_FOPEN_OPEN_EXISTING GD_FOPEN_CREATE_NEW GD_FOPEN_CREATE_ALWAYS GD_FOPEN_OPEN_ALWAYS GD_FOPEN_OPEN_APPEND
A0	Pointer to filename

Outputs:

D0	Status result: +ve: success (Returns file handle) -ve: failure

RAPTOR_GD_FileClose

Closes a file on the mSD card.

Expected Inputs:

D0	File Handle

Outputs: None

RAPTOR_GD_FileSeek

Seeks to an offset in the file.

Expected Inputs:

D0	Handle
D1	Offset in Bytes
D2	Flags: GD_FSEEK_SET: Absolute position from start GD_FSEEK_CUR: Relative offset from current position GD_FSEEK_END: Absolute position from end

Outputs:

D0	Status result: +ve: success -ve: failure

RAPTOR_GD_FileRead

Read from the currently open file.

Expected Inputs:

D0	Handle
D1	Bytes to read
A0	Pointer to data buffer to load into

Outputs:

D0	Status result: +ve: success -ve: failure

RAPTOR_GD_FileWrite

Write bytes to the currently open file.

Expected Inputs:

D0	Handle
D1	Bytes to write
A0	Pointer to data buffer to save from

Outputs:

D0	Status result: +ve: success -ve: failure

RAPTOR_GD_FileTell

Returns the current position in the currently open file.

Expected Inputs:

Handle

Outputs:

D0	Status result: +ve: success - contains the current file position -ve: failure

RAPTOR_GD_FileSize

Returns the size of the currently open file.

Expected Inputs:

Handle

Outputs:

D0	Status result: +ve: success - contains the file size -ve: failure

RAPTOR_GD_FileInfo

Returns information about the specified file.

Expected Inputs:

A0	Pointer to filename
A1	Pointer to file buffer
D0	Flags: GD_FINFO_SHORT_NAME: Get short name plus data GD_FINFO_LONG_NAME: Get long name plus data

Outputs:

D0	Status result: +ve: success -ve: failure

We have also included two simplified functions so that you don't have to manage open/read/close and all the other things associated with them:

RAPTOR_GD_LoadFile

Loads a specified file at a specified address:

Expected Inputs:

A0	Pointer to filename
A1	Pointer to file buffer

Outputs:

D0	Status result: +ve: success -ve: failure

RAPTOR_GD_SaveFile

Saves a specified file from the specified address:

Expected Inputs:

A0	Pointer to filename
A1	Pointer to file buffer

Outputs:

D0	Status result: +ve: success -ve: failure

RAPTOR_ftime_to_ascii

Converts the time bitfield to human readable format:

Expected Inputs:

D0	ftime (16-bit word)
A0	Pointer to output buffer (returns 8 bytes HH:MM:SS)

Outputs: Output buffer is filled

RAPTOR_fdate_to_ascii

Converts the date bitfield to human readable format:

Expected Inputs:

D0	ftime (16-bit word)
A0	Pointer to output buffer (returns 10 bytes YYYY:MM:DD)

Outputs: Output buffer is filled

RAPTORLSP.O Function Calls

RAPTOR_LSP_Init

This function will install and start the LightSpeedPlayer, which is an optional module for both audio generation and jagpad reading. If this module is not used and these functions are required you can substitute another DSP engine, eg ZeroPlayer, instead. RAPTOR does not make any direct use of the DSP and leaves this available to the discretionof the programmer.

Expected inputs:

D0	Call with replay frequency to be used for MODule playback, in Hz

Outputs: None

RAPTOR_LSP_onoff

This function will toggle the sound engine on/off

Expected inputs: None
Outputs: None

RAPTOR_LSP_Sample

This will play a sample as specified by the registers below:

Expected Inputs:

D0	Start address of sample (long aligned)
D1	End address of sample (long aligned)
D2	Start address of loop position (or set to #silence for no loop)
D3	End address of loop position (or set to #fin_silence for no loop)
D4	Sample frequency (must divide by SCLK correctly, eg 7389/14389)
D5	Volume (0-63)
D6	Channel (0-3)

RAPTOR_LSP_playmodule

This will start a module file playing. Not that the file must first be prepared with LSPConvert.exe first.
Details of this can be found here: https://github.com/arnaud-carre/LSPlayer

Expected Inputs:

A0	Pointer to the lsmusic file
A1	Pointer to the lsbank file

RAPTOR_LSP_stopmusic

Checks if music is playing and if so silences it.

Expected Inputs: None
Outputs: None

RAPTOR_LSP_startmusic

Checks if music is silenced and if so enables it.

Expected Inputs: None
Outputs: None